Update index.md #6
Conversation
New draft that explains project outlines, templates, best practices
|
I mainly intended to add content explaining how templates and project outlines (the MVD) are useful. I'm offering this as a replacement for the index.html page, because the templates and MVDs are the selling point of the project. It might be best to pull people in by telling them what we can do for them. |
|
You have some good suggestions and text in here @cwcromwell, but:
|
There was a problem hiding this comment.
You have some good suggestions and text in here @cwcromwell, but:
I think there is too much information for the main index.md file. I think it should be moved to another page which explains the templates.
I think we as a team should firstly build up an outline of the key pages we want to create, and what should go into those pages.
While I think we have an idea about what templates we will write, I think we are yet to decide that too. (More discussion needed there too).
My recommendation is that we don't apply this pull request, but rather insert parts of it into other places.
|
This could be an internal page. It will be easier to revise after the project has taken shape. |
|
|
||
| ### Why? | ||
| ## Project outlines |
There was a problem hiding this comment.
I think the way @cwcromwell frames the project up to this point is excellent.
After this it might be getting a bit to verbose for the scope of a README. In saying that, I definitely don't want to lose this content.
I wonder instead of going into the verbose descriptions of outlines, templates, and best practices, we give the "twitter description" of them at this level, and then put the meat into another file?
| * Improves doc quality and consistency across the board. | ||
| * Facilitates the democratisation of knowledge. | ||
| * Leads to self-empowerment and the betterment of humankind. | ||
| As an example, suppose you have built a new RESTful API service. You could create reference documentation using Swagger and pat yourself on the back. But you could go further and complete the Minimum Viable Docset for a REST API: |
There was a problem hiding this comment.
would this information flow into one of @cwcromwell about-api-overview.md style artilces? There seems like there could be a bit of duplication here.
This is only a terse review from what I've seen while converting @cwcromwell templates so don't take my word for it.
There was a problem hiding this comment.
So we are looking at the main webpage for thegooddocsproject. I believe the landing page should be super concise, focusing only on the key message(s). Readers can find more info from the tabs. Even the current page is more words that I’d like. Examples of simple messaging on your landing page http://geonode.org/ or https://atom.io/ . For our story about the project, or what is in our templates, I feel we should point readers to our other pages, like “howtos” or https://thegooddocsproject.dev/about.html
|
notes from 3 June meeting:
|
New draft that explains project outlines, templates, best practices