Chapters should be reordered

In my opinion, the documentation should be reordered. The most commonly referred-to information should come first. I found the Design chapter to be very far from the first thing I wanted to read. For example:

1. Introduction
2. Reference information about hardware
3. Reference information about software
4. Instructions on setting up hardware, plugging in, getting a shell, etc.
5. Information about software development that's applicable to the phone, for example, say, descriptions of public phosh/oFono/Calls/virtual keyboard/etc. APIs
6. Instructions on setting up development environment(s)
7. Instructions on building software (current "App Development" chapter)
8. Guidelines for development (like Design)
9. Information on getting apps published

changed the description

I agree here. I thought I'd filed a similar issue recently but can't seem to find it.

mentioned in merge request !63 (merged)

It looks like issue #9 (closed) will relate to this.

@david.boddie has created a good proposed structure here: https://source.puri.sm/david.boddie/developer.puri.sm/wikis/home. The documentation team's plan is to move forward with this.

My plan is to do a restructuring in a branch and gather feedback from the team. Then we can argue about whether hardware should come before software, etc.

But feedback is welcome at any time.

https://source.puri.sm/david.boddie/developer.puri.sm/wikis/home

For me, this page says "This project has no wiki pages"

@bob.ham ok I just granted access to the Librem5 group so try again.

@bob.ham Sorry, I renamed the page, so it got a new URL.

As I said in the issue description, IMHO "the most commonly referred-to information should come first" which means the reference information would not be at the back in appendices but at the front.

Describes the purpose of this documentation.

I think that needs to be clarified before we can discuss the ordering.

Also note that any reordering breaks existing links we sent out in e.g. matrix.

Before doing the reordering it'd clarify who is the target audience. An app developer working mostly on his laptop has different needs than someone working with the actual hardware.

So who is this document for?

I'm open to the idea that it could be a "reference first" manual, but then we're talking about two different documents for two difference audiences.

I think we're going to have to figure out the linking problem at some point because we need to deal with issue #42 (closed) at some point.

I'd say the developer documentation is primarily targeting developers that want to write apps for the Librem 5, with little to moderate experience. Some of these folks will have backed us and are getting a dev kit, others will need to rely on the qcow2 we produce.

Issue #42 (closed) won't get resolved for quite some time. The history here is that after that issue was opened, it was collectively decided that we need a separate domain for user documentation so I setup docs.puri.sm with a base structure. However, the thinking is that eventually there will be developer documentation for these other products and we (the documentation team) will be the ones to help write it. But for now, the Librem 5 launch (incl. dev kit) is our top priority. Once the Librem 5 has somewhat stabilized, we can think about switching gears to write some developer documentation for the other products.

Yeah. Targeting app developers first is IMHO the right thing. The reason I brought this up is that I would structure the document differently than proposed here and would much more talk about the software stack and emulators first.

I understand the different perspectives on this. Some people will want to read about the hardware and get an idea of what is present and supported, then move on to how it is integrated with the operating system. Others will want to read about how the software stack is assembled. Some readers will just want to get up and running, get a taste for how app development works, then dig into the references/guides for the features they are interested in.

I think this is where a linear document doesn't help us because we will never agree on what needs to come first. I feel that it would be better to branch out from a starting page to the documents for different audiences and focus on what those documents should contain. This can be done in parallel, though I think we need to prioritize developer kit information right now.

It would be ideal if we had a few different "jumping off points" from the documentation main page, so that a user can sort of choose their own adventure, like https://developer.elementary.io/. However how to implement this idea correctly might prove to be an obstacle that keeps us from updating the overall structure now.

So in my opinion, we should go forward with @david.boddie's improved structure now and focus on catering to various starting points later.

If we consider the different chapters to be separate documents then that might help solve the ordering problem. I'm much more concerned about getting the right information in each chapter than deciding on the best order for them. I think a jumping off page is the right way to do this, and it's also how many other projects organize things.