How/where/what to document

dwyl / contributing

:clipboard: Guidelines & Workflow for people contributing to our project(s) on GitHub. Please :star: to confirm you've read & understood! :white_check_mark:

86 stars 9 forks source link

How/where/what to document #69

Open jay-meister opened 7 years ago

jay-meister commented 7 years ago

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.

mk4111 commented 7 years ago

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.

iteles commented 7 years ago

@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!

nelsonic commented 7 years ago

@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. 👍

jay-meister commented 7 years ago

@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.