Plan for Dev Docs reworking

[adamfowleruk]

Hi all,

I was reviewing the /development/ docs on the website and think I'd like to re-work the folder significantly. Wanted to document this here to gain feedback before forking and sending the world's biggest PR for the changes...

General approach: Segment the documentation in to a logical order in consistent levels of detail to make it easy to consume in chunks, and re-work so all content has the same format, theme, and is on the website as html (not PDFs etc.)

A new developer should be able to start at the top and work their way down until they're competent at developing the code in the area they are interested in.

Once done, also change all links throughout the website to point to this single location for development documentation.

The contents would change to:-

Introductory Information

• High level Haiku OS design [New, basic architectural intro]
• The Haiku ecosystem [New: Haiku OS, Apps, ports, and BeOS support. Covers off where things live in OS vs. apps]
• Finding Haiku source code [New: Builds on the above]
• Meet the developers [New: introduce some core devs, have them talk about why they work on Haiku, why it's awesome, etc.]

Leaning to Code in C++

• Never written code before? Learn to code with Haiku course [re-work DarkWyrms intro course for C++, add intro to Paladin IDE potentially to make it really easy - Paladin should include both templated and complete samples for each lesson]
• Intermediate C++ course with Haiku [re-work DarkWyrms 1-5 lessons of his programming with Haiku Course]
• Advanced C++ in Haiku course [New: Talk about cross compiling, Makefiles (I'm assuming they're using Paladin IDE or similar until now), libraries vs apps, using libraries, using 3rd party API]

Starting to Contribute

• Milestone & Bug Tracking [New page, with all links to Trac explained and contained within it]
• Ideas for what you could work on [Was: Getting started]
• Setting up a Haiku development environment [New section: For Windows, Linux, and Haiku native developers - re-work the dev tools and cross compiling docs]
• Debugging within Haiku [Was: Debugger reference manual, converted to html]
• Introducing yourself & Getting Help [New: IRC info for devs, who to talk to, how to say hello and state your aims]

Developing Applications for Haiku

• A new app, or contributing to an existing app? [New: Discuss that the app may already exist but need help to revamp from the HaikuArchived, or ports, or...]
• Porting guide [New?]
• Introducing the Haiku APIs [New: High level intro, before dropping in to the book]
• Common Patterns for Haiku app development [Re-working DarkWyrms lesson 12+, waddlesplash's Layout API docs, links added to the Book]
• Preparing your app for publishing [New: Covers translations, Icon guide, etc.]
• Packaging your app [New]
• Publishing your app [New]

Haiku Development References

• Haiku Coding Guidelines
• Human Interface Guidelines
• Development FAQs [Exists]
• Sample code projects & Templates [New: Perhaps a holding page mentioning templates that will exist within the Paladin IDE eventually. It's an aim there to provide all the templates and sample a Haiku Dev could need]
• BeGeistert Conference [New: Mention dev done at conference, link to BeGeistert page]

Building & development the Haiku OS itself

• Introduction to the Haiku Kernel Design & Standards [New: Also include 'why c++?']
• Introduction to the Be Filesystem Design [New: Include info about attributes]
• Getting the source [Link back to intro source page]
• Building Haiku guide [Re-work building guide in to sections under here]
• Creating your own liveusb image guide [New?]
• Building Drivers for Haiku guide [Update existing video drivers guide, perhaps get a basic driver working]
• Porting freebsd driver guide [New?]
• Porting Linux driver guide [New: Needed?]

More will probably occur to me once I've started. Note: NONE of the items marked New will be added until AFTER they are written. Only thing worse than no documentation is unfinished or placeholder documentation!

[pulkomandy]

This looks like it will also replace/complement pages currently under /community/. There is also a mix of developping the OS itself, and developping apps for it, which are somewhat similar but not always identical.

Also, what is the interaction with api.haiku-os.org? Whike the Haiku Book is more meant as an API guide, it has (like the be book) general introductions to each kit, and I think could be extended with the rationale and more general overviews of the design, expected way to architecture an application, etc.

[adamfowleruk]

I see the Haiku Book at api.haiku-os.org as API documentation. It has package overviews, class documentation, and links between classes and functions. There are no code samples or working apps. I'd be tempted not to pollute the API documentation with anything other than API documentation. It may be good to link back from API documentation to guides, tutorials, or samples that mention those classes though. All the 'updated' documentation guides should also have deep links to the API docs whenever they mention a class or method.

I'd also be tempted to link the /community/ Getting Involved pages on development in to the specific places in the /development/ area. (i.e. these links: Documents for developers, translating, developing, documenting, testing, designing)

That way everything to do with development sits under /development/, with links coming in from other sections rather than more pages.

[waddlesplash]

First stage of this was merged, and the rest of the changes can just go to the website repo or get discussed as appropriate on IRC beforehand.