contributing
contributing copied to clipboard
dwyl
How/where/what to document
I have always felt that there should be more of a process/guidelines when it comes to documenting stuff. I imagine there is a lot overlap with what you want to be documented across projects (permissions/routes/user-flows/getting-started/...).
It would help to have a specific guide to follow so that I know where to add this piece of information rather than just stick it on the end of a potentially long readme.
Following on from @JMurphyWeb 's description, I think putting the 'Questions' section at the bottom could make the README.md flow better. I also think that that's usually where people intuitively look for Questions/FAQ sections.
@JMurphyWeb Agree that this would be an excellent addition. As you're fresh off a client project, could you please drop a few bullet points here as to what you see as imperative for documentation?
A PR would be grand but if you don't have time for that just yet, this would be a great start!
@JMurphyWeb thankyou for raising this issue. 😍 relates to: https://github.com/dwyl/contributing/blame/4f38e20b95eb6d3a950e6f8f9f44bbd977ae87d8/README.md#L118-L129 Would be stoked to see a PR improving this. 👍
@iteles I feel like this is something I have never really got right but am happy to put my thoughts forward.
Key bits of documentation for me:
- Getting started (developer docs)
- What the application does and a basic user flow (this could be aimed at someone trying to understand the app without ever opening it up so possibly at a future client/employer/developer should contain screen shots of the main user flows [not necessarily every view])
- Data structure (technical docs)
- Routes and permissions
- (Link to) wireframes
Then it still feels like you would need a:
- Miscellaneous (containing anything that does not fit into a category but is important for a developer to know)
That's what I can think of off the top of my head.