Merge lp:~dholbach/help-app/1426011 into lp:~ubuntu-touch-coreapps-drivers/help-app/trunk

[Daniel Holbach]

[lp:~dholbach/help-app/1426011]

60. By Daniel Holbach on 2015-02-27

replace tabs with spaces in directory tree diagram

[David Planella (dpm)]

LGTM, good work with the documentation!

review: Approve

=== modified file 'HACKING'
--- HACKING	2015-02-26 16:23:58 +0000
+++ HACKING	2015-02-27 08:59:48 +0000
@@ -1,6 +1,66 @@
 Welcome to Help for Ubuntu devices!
 ===================================
 
+What are we doing here?
+-----------------------
+
+In a conversation amongst Ubuntu phone enthusiasts, we decided we wanted to
+create a good way in which we can aggregate information, tips and tricks and
+suggestions for using Ubuntu devices (like the phone or a tablet) easily.
+
+The end result being new Ubuntu users who can
+
+ * find out more about how to use their phone
+ * quickly be more productive
+ * find new things
+ * get started easily because the information is available in their language
+
+Thanks a lot for your interest in helping out!
+
+
+How does this all work?
+-----------------------
+
+Our work-flow is a bit special, so bear with us for a while. If you just want
+to start adding content, skip this section. The sections below should 
+probably be enough for that.
+
+We had a couple of requirements when we started this project:
+
+ * easy to add/modify content (we decided to use Markdown)
+ * easy to translate content (we decided to use Launchpad)
+ * easy to create different builds (one for the phone, one for an online
+   site, like *.ubuntu.com)
+
+On the way to implementing all of the above, we settled on a mixture of
+pelican and po4a on the content side, the Ubuntu HTML5 UI toolkit and
+the Ubuntu Web Guidelines on the display side.
+
+ * po4a is used to extract translatable messages from the Markdown 
+   content, so that we can get .pot and .po files which are understood by 
+   Launchpad. We also use po4a to generate translated Markdown files.
+ * pelican takes care of generating HTML from the translated Markdown
+   files. It can build into different output directories, using different
+   themes, which is very handy in our case.
+ * The Ubuntu HTML5 UI toolkit is used for the phone app.
+ * The Ubuntu Web Guidelines for the build which we will put up on an
+   Ubuntu site very soon.
+
+
+Directory structure
+-------------------
+
+
+├── app                 ← Everything related to the devices app.
+│   └── www             ← The viewable content of the app.
+└── edit-here
+    ├── content
+    │   └── pages       ← Here is the place to edit the content.
+    ├── po              ← Translations.
+    └── themes          ← Themes files, both templates and css/js.
+        ├── phone       ← Phone/device app theme.
+        └── web         ← Online build (.ubuntu.com) theme.
+
 
 Prerequisites
 -------------
@@ -10,6 +70,9 @@
   sudo apt install python-pelican po4a make bzr \
 	ubuntu-html5-ui-toolkit python3-polib
 
+This will install the necessary files, so you can build the app or web build
+locally and check if your changes actually make sense and look and work well.
+
 
 Editing
 -------
@@ -17,7 +80,7 @@
 This app is structured in a very simple way. All the content is and all your
 edits happen in
 
-	./edit-here/content/
+	./edit-here/content/pages/
 
 The markup for the text is Markdown, which is very easy to learn. Just have 
 a look at http://daringfireball.net/projects/markdown/ and some of the 
@@ -56,6 +119,10 @@
 
 Find the resulting files in ./web in the top-level directory.
 
+We plan to make use of 
+http://www.w3.org/International/questions/qa-apache-lang-neg for publishing
+this on the web.
+
 
 Code, bugs, etc.
 ----------------
@@ -71,6 +138,6 @@
 	make update-pot
 
 If you want to get help with the app or anything else, ask the fine folks
-in #ubuntu-app-devel - for example dholbach, mhall119 or dpm.
+in #ubuntu-app-devel - for example dholbach, balloons or dpm.
 
 Thanks a lot for helping out!