Topics

documentation_roadmap


David A. Wheeler
 

On Tue, 20 Jun 2017, Wheeler, David A wrote:
Some projects don't plan to make any changes; some plan to make modest
changes; some plan to rewrite everything & the API is going out the window.
It's helpful for users to know where the project intends to go. Not
everything goes as planned, but at least the user has an inkling.
Does that help?

Daniel Stenberg:
Yes, thanks, that helps. It does however make me question the value of the
criteria.
*Please* feel free to question! It's why this mailing list exists :-).


It asks for a document to be present that lists things that a project
might or might not do at some point.
- project A lists things in the roadmap for several years that haven't
been implemented
- project B doesn't have a roadmap document but develop things
Project A is still considered having the (much) better practice? Why?
I think this quote sums up things:
"Plans are useless, but planning is indispensable." - Dwight D. Eisenhower

As expanded here from DrupalCon:
https://events.drupal.org/baltimore2017/sessions/plans-are-useless-planning-indispensable
"The value of a plan lies in the act and effort of planning: in doing so, you gain understanding ... Planning encourages situational awareness through learning and discussing strengths, weaknesses, opportunities, threats and a flexible strategy that can tie them all together. A good plan establishes a vision, with goals and supporting objectives, and provides context and directionality so the team can move forward and be supported without being locked in."

Clearly execution is *way* more important than just planning. But planning, and sharing your thoughts with collaborators, can increase the likelihood that everyone will work in the same (general) direction. Even just saying "we're in maintenance mode, and focusing on small incremental improvements" can help people understand things.

Also: In principle this criterion isn't difficult. Just figure out your current plan & write it down. The *real* challenge is the planning (to figure out your plan). The hope is that this criterion will encourage people to think that through; it encourages people to step back & think about the larger goals for the project.

--- David A. Wheeler


Daniel Stenberg
 

On Tue, 20 Jun 2017, Wheeler, David A wrote:

Some projects don't plan to make any changes; some plan to make modest changes; some plan to rewrite everything & the API is going out the window. It's helpful for users to know where the project intends to go. Not everything goes as planned, but at least the user has an inkling.

Does that help?
Yes, thanks, that helps. It does however make me question the value of the criteria. It asks for a document to be present that lists things that a project might or might not do at some point.

- project A lists things in the roadmap for several years that haven't
been implemented

- project B doesn't have a roadmap document but develop things

Project A is still considered having the (much) better practice? Why?

--

/ daniel.haxx.se


David A. Wheeler
 

So for silver level, a project MUST have a "roadmap".

Does the project also have to actually implement or work on any of the items
in the roadmap? If so, to what degree? If not, what's the purpose of this
criteria?
Text:
The project MUST have a documented roadmap that describes what the project intends to do and not do for at least the next year. [documentation_roadmap]

We tried to define the purpose of this criterion in the details:
Details: The project might not achieve the roadmap, and that's fine; the purpose of the roadmap is to help potential users and constributors understand the intended direction of the project. It need not be detailed.

Some projects don't plan to make any changes; some plan to make modest changes; some plan to rewrite everything & the API is going out the window. It's helpful for users to know where the project intends to go. Not everything goes as planned, but at least the user has an inkling.

Does that help?

It might be useful to look at the BadgeApp's roadmap:
https://github.com/coreinfrastructure/best-practices-badge/blob/master/doc/roadmap.md

You'll notice that at this point we do *not* have grand plans for the BadgeApp - we wanted to add internationalization & higher levels, and did that. At this point we're expecting to do more refinements than big plans, and that's fine... just let users know that.

--- David A. Wheeler


Daniel Stenberg
 

Hi,

So for silver level, a project MUST have a "roadmap".

Does the project also have to actually implement or work on any of the items in the roadmap? If so, to what degree? If not, what's the purpose of this criteria?

I think this is a bad criteria.

--

/ daniel.haxx.se