coapp-developers team mailing list archive

[Mateusz Łoskot <mateusz@xxxxxxxxxx>]

On 19 December 2011 21:12, Garrett Serack <garretts@xxxxxxxxxxxxx> wrote:
> I've pushed up the new CoApp.org website.

Congrats!

> I'm aiming for a little simpler layout for content, and a trivial path to
> promote docs from the wiki to the website.

It looks great, clear, slick!

> The previous incarnation was running on Jekyll (written in ruby and the
> syntax highlighter was written in python). Together that was about a 190mb
> install to get up and running (along with a  lot of little steps!)

Whew!

> This site uses (my fork of) DocPad -- it's a static site generator written
> in node.js.

Nice. I think project websites have little or no dynamism.
Blogs can be syndicated or installed separately, under site.org/blog etc.

> I added the triple-backtick (```) color-syntax highlighting that
> github-flavored-markdown uses along with support for embedded javascript
> (.ejs), and a bunch of other little fixes.
>
> You can clone the source from github, and run the tool to generate the
> static site without having to install *anything* (well, other than git!)

Bombastic!

> Next, I'll start  by putting in docs the how-to modify the website right in
> the website : http://coapp.org/pages/contribute.html ;(see the stuff under
> I can help write documentation or add to the website)

Is there file/way to find out tree of table of contents?
Or, can we discuss and decide on it?

> If you have fixes or ideas, feel free to post 'em or send pull requests. :)

Here are my questions and comments related to structure of content:

My proposal of top-bar menu:

About | User | Developer | Packages | News | Community (or Help or Support)

Front page looks great.
I'd only add CoApp Quickstart section like here http://git-scm.com/
Then CoApp Quickstart has two or three panels with command line short
sessions for:
- Find package
- Install package
- Update package

I'm not sure about Learn vs Contribute nodes.
Wouldn't it be clearer thus easier to find & navigate by folks if
Learn & Contributed
was transformed this way (* denotes name of sub-node, # is my comment
on what is included):


About
* What is CoApp?
    # Let people to find out if they need/like CoApp and need/want to
use it, in 60-120 seconds.
    # History, motivation and rationale Why CoApp exists.
    # Very hHigh-level, overall structure of project, infrastructure, etc.
* CoApp Team
    # Who is behind CoApp, project owner/manager, people, organisations, names
* CoApp Website
    # Web-dev oriented contributors should look here
* License & Copyright
    # All the difficult questions are answered here
* Contact
   # Twitter, ..., links to Community & Support section (explained below)


User
* Download
  # Obvious, where can I find CoApp (source package, binaries)
* Installation
   # How to install and configure CoApp environment for end-user
* Usage
  # Explanation of main CoApp workflows for end-user, How-To
* Tools Reference
* Troubleshooting
   # Solving problems about using CoApp, no developers talk!


Developer
* CoApp Design and Architecture
  # In-depth discussion dedicated to developers and potential contributors
* CoApp Development
  # Env setup, requirements, how to build, how to contribute code to CoApp
  # How to contribute documentation to CoAapp
* CoApp Packaging
  # Exclusively dedicated to those who want to create new packages for
CoApp, not bothered with hacking CoApp, code contributions, etc.


Packages
  # I guess it is dedicated to anything to package repository display


News
  # Releases, Blog, etc.


Community & Support
* Got a question?
  # mailing list, IRC,
* Got a bug?
  # In CoApp? In package?



Why this way?
Because this is what I personally expected to find when I found CoApp
project on Web and wanted to browse about it.
Because this is how I *personally* map CoApp knowledge in my own head
:), so I propose it like this.


Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net
Charter Member of OSGeo, http://osgeo.org
Member of ACCU, http://accu.org