Chuck Taylor
Seattle
chuck....@newsdex.net
Personal page: http://bit.ly/f8DHHK
206-396-1017
Twitter: http://bit.ly/hsCpc4 | Flickr: http://bit.ly/gaG6EW | Blog: http://bit.ly/f0NGf5 | LinkedIn: http://linkd.in/gEyWgi | Where I work: http://www.heraldnet.com/ | View from the newsroom: http://bit.ly/eD167Y
Newsdex Seattle - Social network metrics for media: http://seattle.newsdex.us
Based on my experience I would like to make a few suggestions. Mind
you, I only know so much and it's always so easy to point fingers
without having anything better to offer. I also might have missed out
something cause really Git and Github is a jungle. I've spent
countless hours going thru forks and branches trying to find the
"latest thing" and pretty much given up on it.
- My first suggestion is therefore to update the masters as frequently
as possible. It's fairly easy to clone :-)
- I've stumbled upon some docs scattered around. Getting them
together in one place would be a huge improvement. It doesn't have to
be fancy. Simple text files work like a charm. Just update
frequently.
- When writing docs, keep in mind that the readers don't know as much
as you guys about publishing, let alone the code. Some things might
be obvious to you but not the average reader like me.
- About the bug reporting system.... At this point an email address
(bu...@armstrongcms.com) would be great. At least there would be a
place to report bugs and perhaps offer solutions. A textfile with
unsolved bugs and solved would be great to in order to avoid
duplicates. Too fancy tools tend to create more problems than they
solve.
Suggestions on the docs.
- Installation is very simple and the docs (readme) explain the
progress. There might be some problems though in various systems -
especially related to virtualenv. I ran into problems with PIL in
ubuntu 11.04 for instance. One cannot cover everything.....
- Start from the end user and work from there. This also gives the
programmes the general idea. Focus on the core and essential
applications like articles and images.
+ Explain the end product. What does a web-publishing look like.
What are the elements in there. There are sections and columns in the
layout for instance. An image would help.
+ Explain the workflow in Armstrong. You write articles, upload
images and then what? You create wells and they are used to populate
columns?
+ Django templates and css. Where are they located.
+ Templatetags. What are the built-in templatetags and how are
they used. I really was expecting to find a render_well "type"
somewhere to put in the template to populate columns. But then again
- I really don't know how things are thought.
+ What is built-in and what needs to be programmed to make use of
the basic applications.
At this point one has the site up and running, able to put in data and
try things. Again - the demo is great. It needs expanding (I
strongly suggest including image handling) but a good starting point.
May I suggest perhaps showing how to list the latest articles on the
frontpage with a thumbnail and a summary?
What next.
- As a programmer I'd really like to see some hierarchy overview.
There are a lot of abstract classes, base classes, mixins and stuff
and for an outsider it's murder trying to figure out what gets done
where.
- What does an app need to interact with the core (render functions and such)
- What views does one need to write etc.
I think I'll stop here for now. Rome wasn't built in a day and at
this point I'd just be happy to have enough docs to understand the
basics so I can work my way from there and perhaps put in something
useful.
Best regards and again, many many thanks for your excellent work.
Bjarni.
Niran Babalola
Director of Technology
The Texas Tribune
512-716-8699 — Office
775-576-4726 — Mobile
http://www.texastribune.org/
I'm not going to be much help in documenting setup or configuration if command line is involved. I'd be better suited to explaining what Armstrong does once installed and how to work with it. If I'm able to get an installation up and running, I'll probably dive into that.
- When writing docs, keep in mind that the readers don't know as much
as you guys about publishing, let alone the code. Some things might
be obvious to you but not the average reader like me.