[LEDE-DEV] [RFC] A new developper documentation for OpenWrt/LEDE

[Rich Brown]

Hi all,

Although I'm not a developer, as someone who cares a lot about documentation, I have a couple thoughts about this proposal.

1) "Throw out all the old stuff, and start fresh." It's easy to propose, and maybe even a good idea. But it's worth asking why don't we already have good dev docs...

- Are we lacking the incentive for people to write docs?
- Has the process been too fluid to bother documenting?
- Is it too hard to write them?
- Is it too hard to post the document? 

What do committers say about their reasons for writing/not writing docs?

2) Use of git vs wiki for developer docs. I'm a fan of using a wiki for documentation. It's easy for any member of the team to update docs as needed, whether for a whoesale update, or just fixing typos. (I'm on a project where we update the site by committing to a git repo. The site is quite far behind the state of development of the project. This *may* be because of the small number of people who have commit priv's, but it might also be that the revise-and-commit process (and revise and commit, and revise and commit again, ad infinitum) is painful with a git repository.

3) Putting the dev docs in the current LEDE wiki keeps it all together, and makes it easy for people to make links from advanced topics/HOWTO's to link to deep documentation.

4) But maybe the LEDE development process has settled down, and now is the time to start documenting all the details. It's certainly true that this proposal envisions the developers/committers would have that commit privilege, so that's less of a hurdle.

As I said, I don't have a dog in this fight. I would lean toward a wiki instead of a publish-from-git scheme, but would defer to the judgement of those who're going to use the system.

Best regards,

Rich