[HTC Sensation] Manko10:
Important: The docs are up. The live copy can be found on http://docs.insertcoin-roms.org/ and the Git repository on https://github.com/Manko10/InsertCoin-Docs/. For information on how to participate, see the wiki.

Hi,

This thread is related to the InsertCoin ROM by baadnewz (see this thread: http://xdaforums.com/showthread.php?t=1198684). Since I haven't written 10 postings yet, I can't post to that thread nor create a new one in that forum.

InsertCoin has become a quite popular ROM for the HTC Sensation. It has had 200,000 downloads yet and numbers still raise. With increasing popularity it becomes more and more difficult to get hold of information you need concerning installation, problems, modification, tweaking etc. The result is a very high number of redundant questions on the forums and confused newcomers.

The project

Thus being said, it is time to create a good and centralized knowledgebase which helps new users to dive straight into using InsertCoin, keeps the development thread cleaner and helps to push the project forward since energy can be focused more on implementing new features and fixing bugs than on answering the same questions all over again.

baadnewz attempted to launch a Wiki once, but it ceased and shut down (as well as the whole baadnewz.eu server which was the last more or less valuable resource for help outside XDA-Developers.com).

Now my idea is to create a new official InsertCoin documentation project. I talked to baadnewz and he assured it would be promoted and integrated into the official website once it comes to life. The project I'm heading for is a community-driven one. I would work for it as much as I can but I can't do it alone. I'm not experienced enough in many (especially technical areas) of InsertCoin development and Android development in general. There are many things to learn about InsertCoin. And to be honest: I also don't have the time to write all the stuff by myself. Once I had written everything, it would already be outdated. So this project is only possible if other people participate actively.

How shall the documentation be implemented?

I thought of a project hosted on GitHub. Users can fork the project, make changes and send pull requests. For infrequent submissions, we could also provide a special submission form.

A staging server would then pull the HEAD revision regularly, format it and publish it as a website.

Sounds complicated? But it isn't. Git is pretty much straightforward and also users without technical knowledge can learn it very quickly (yes, there are great graphical tools for it). And of course, the documentation would also include a noob-proof guide to contribution.

But why Git? Why not a Wiki?

A Wiki might seem to be easier, but in fact a Wiki has to be updated regularly. Patches for bugs and security holes have to be applied. Additionally, we had to fight spam. Especially when we use some well known software such as MediaWiki, spam bots would love it. That can be a lot of work.

But the main reason is portability. A Wiki is a Wiki, nothing more. Exporting the contents into other formats would be a tedious process. However, when using plain text files with a simple markup language such as Markdown, they can be exported to all formats we like. Not only can the staging server parse it to HTML, but it can also be exported to PDF, CHM files (does anybody still use these?) and many more formats.

All right, but what is to be documented?

Well, a lot. Things I have though of are

Installation

Where to get InsertCoin ROM?

Which version?

How to flash InsertCoin?

How to upgrade from previous versions?

To wipe or not to wipe (and when)?

Kernels

Which Kernels are there?

Where to get them?

What are the differences?

Advantages/disadvantages of specific Kernels

How to install a new Kernel/revert to stock?

What is a Kernel and why can't I install it via the Market? (dumb question, yes, but important to know)

Known problems

Any reported bugs still present in version X?

How do I report my own bugs?

Why does feature Y not work (and never will)?

Features

Why to choose InsertCoin?

How to submit feature requests?

Requirements

What do I need to run InsertCoin?

Which baseband version do I need?

Where do I get a new baseband version and which one to choose?

Does it work on device X, too?

Which is the oldest supported version for custom kernels?

Add-ons

Which add-ons are there?

Where to get them?

How to flash them?

What to be aware of?

How to get rid of malfunctioning add-ons?

Customization

Which themes are there?

How do I install them?

How do I revert back to the default theme?

How to set up custom boot splash and boot animation?

FAQ

Things users ask all the time

Things users might ask regularly in the future

Milestones

Any planned features for future releases?

How many ROMs to release tomorrow?

Participation

How to submit patches?

How to improve the documentation?

How to pay a round for baad?

General information

What else could be valuable information?

How do I backup and restore my data most efficiently and least time consuming for upgrades which force a full wipe?

etc.

The list goes on. It's up to us how much it'll grow. Make suggestions please. Don't hesitate! :-)

And now you come into play!

Do you think, such a project could become a success? Do you have suggestions, ideas, criticism? Post it here. Please.

Would you like to contribute? Post an answer. You would be one of the glorious pioneers.

If I get enough positive feedback and support by people who want to contribute I will start working on the base system, set up the Git repository, write the staging software and launch the project. If not, it would have been at least worth the effort. But you would contribute and give something back to the community, wouldn't you? Sure, indeed...! ;-)

Cheers

Manko10