Active
Project:
Open Atrium
Version:
7.x-2.x-dev
Component:
Documentation
Priority:
Normal
Category:
Task
Assigned:
Unassigned
Reporter:
Created:
5 Feb 2014 at 17:41 UTC
Updated:
21 Jun 2016 at 21:39 UTC
Jump to comment: Most recent
Currently there are 2 places where documentation can be found:
1) Technical information
2) End user information
This issue is aimed at improving the Technical information pages.
1) Identify major topics that need documentation and create a page in the Open Atrium distribution documentation
2) Create an issue for each page so we can discuss what is needed for that page. List them in this issue for reference.
3) Update the documentation
Open Atrium 2
Installing or updating Open Atrium *Finished*
Managing configuration changes
Open Atrium permissions *incomplete*
Webinars summaries
List of sites using Open Atrium
Comments
Comment #1
Argus commentedYou fail to mention what documentation you did read. For instance did you visit http://docs.openatrium.com/ and read the info there? Did you watch some webinars? Did you follow the Tours that are available in the application?
Comment #2
dillweed commentedYes, I have viewed the documentation on your mentioned site. I have watched a couple of the webinars. However, a webinar is good information but doesn't provide a good way to find a specific answer to one question because a webinar is hard to index. The site tours are more specific to the end-user and not an admin.
Comment #3
Argus commentedMore technical documentation is planned here: https://drupal.org/node/2169671, it is indeed not finished by far. But I wouldn't expect a detailed book on Drupal there. It won't solve that shortcoming.
I imagine it also won't provide the answer to detailed questions like "what is the difference is between Open Atrium Groups and Open Atrium Organic groups", but rather an administrators and developers guide to the use of OA and how to adjust it.
I would suggest you open seperate issue's for each question you have, try to explain what you do understand and people will fill up the gaps, or at least find out in collaboration what the correct answer is. Most of us are learning Open Atrium just like you are.
Comment #4
mintra commentedI totally agree with dillweed, the documentation is spread all over the place and something as simple as changing the logo at the top of the page is just not achievable even for experienced computer people.
Comment #5
mpotter commentedRemember that this is an *Open Source* Product so anybody can add documentation or patches. The node mentioned in #3 is open to editing by any member of the drupal community.
We have honestly contributed far more documentation than most other distributions via many mechanisms, such as written, webinars, drupalcamp trainings, etc. All for free.
(changing the logo on the page was actually covered in a recent webinar)
So, I welcome people to contribute so I can personally stay focused on fixing bugs and making technical improvements. But I also expect people to actually read all the current docs and watch all of the existing webinars before complaining about the lack of information.
Comment #6
Argus commentedI'd be in for that, a combined effort to improve the doc pages. We would need to define what info should be in there, discuss the structure of the documentation pages and then do the actual work of writing them.
Comment #7
dillweed commentedI may have come across as complaining, so I apologize for that. I do appreciate all the work put into this product and I feel that Open Atrium would greatly benefit our company. The webinars are great, they just hard to search through. I want to contribute, I wish I knew more about php programming, but unfortunately, just like everyone else trying to earn a dollar, my time is limited.
And yes, drupal's overall documentation is all over the board and Open Atrium is a lot better documented than most things drupal. I was just thinking that more written documentation would enhance an already good product. So it's more of an appeal to the wider community to help out. I'll do what I can, I'm not a programmer, therefore, I don't know what contributions I can make that will be meaningful, but I can try.
Anyway, I'll keep plugging away at my problems, thank you for your work.
Comment #8
Argus commentedNo worries dillweed, you pointed out a real shortcoming. Don't hesitate to create an issue if you have questions.
Actually one of my thoughts was to make overviews of the webinars, describing what is discussed and point to that spot in time. That would make them more accessible and make it easier for people to find what they are looking for instead of having to browse through an entire webinar.
Comment #9
jakeschlachter commentedHi all,
As a new user of OA2 who
has recently come up to speedis still coming up to speed on the platform, I feel both capable and honor-bound to contribute to this effort. OA2 is an amazing platform, and I am obliged to give something back.The first major challenge I had was wrapping my head around information architecture decisions. Since I am migrating an existing, heavily used and abused, D6 OG site into the nice, neat, orderly OA2 hierarchical boxes, this was no small feat. I relied upon multiple viewings of the "Planning Your OA Solution" webinar of Nov 20 2013 with Karen Borchert. But I also first had to just set up a sandbox site to play around with core concepts of Spaces, Subspaces, (and more Subspaces), Sections, OA2 Groups, and users.
I think that OA2 is fundamentally complex enough that you don't necessarily learn from reading, per se, as much as you learn from experiential (self) training -- any more than you can learn programming by reading a book but not writing code. We the community could facilitate the learning process by capturing case studies of e.g. design decisions -- what we made and why we made it -- and then having discussion with each other about the pros and cons of the decision, exploring alternatives, and so on.
If there is a suggested forum for that (d.o? wiki page? issue queue? stackexchange?) I would be happy to kick something off over the next several weeks.
Comment #10
Argus commentedLet's start with a blank sheet here.
Comment #11
Argus commentedComment #12
Argus commentedComment #13
Argus commentedComment #14
druplicate commentedPart of the problem is that OA has a lot of moving parts simply because it's based on a number of "tool sets", like Panopoly, Features, and Organic Groups with many other modules contributing. So it's inescapable that it's hard to learn since configuration, structure, etc. is spread all over the place and that lack of cohesiveness complicates the learning process. All highly integrated distributions suffer from this malady.
This also makes documentation difficult since one feels compelled to explain how Panopoly, Features, and OG fit into the puzzle, a ton of work. One way to deal with this overwhelming task is to begin by chronicling the history and evolution of OA2. Explain what the original goals were, how and why the various tools were chosen, and what sort of information architecture these tools were designed to address. Just trying to figure out what sort of IA one needs is often the biggest task, so again, that's necessarily part of the documentation challenge.
So while the builders of OA are basically asking the user community to write the docs, it's not that simple and a bit unrealistic. It's too complex with so many interacting components. Once you've described the evolution of OA2 then that constitutes a framework that users can realistically add to, one facet at a time.
When I was in engineering school I had difficulty learning some advanced math until I discovered a 3-volume set called "The History of Mathematics" that explained why Newton, Leibniz, Euler and many other famous mathematicians did what they did - they were trying to solve real world problems by creating the necessary tools, such as algebra, and differential equations. Just knowing that and following the course of discovery over many years made it a lot easier to wade through the hieroglyphics and focus on the tools they created. The history established a framework in my mind that tied everything together. Stare at one piece of a jigsaw puzzle and you'll know nothing about the finished mosaic. Math was suddenly a lot less abstract, but I digress...
If users know why you chose the various tools and the methodology, then the anxiety of trying to understand the framework is lessened. There comes a point for everyone trying to learn a complex distribution, thinking it might just be easier to roll your own because at least you will have thought through the process of achieving the project goals, in an organized fashion.
Just for my own edification I was getting ready to write down everything in the webinars and organize it. I agree webinars and videos in general are great for overviews but lousy for actual learning. I've ranted on this too much already in various places (I signed up for Build-a-module and dropped it soon after because you can't learn from videos - no easy or functional way to index, add to, or update them, etc.).
So that's my recommendation - create the framework first by outlining the project history vis-a-vis the goals. Then users can fill in the details much easier.
For starters:
Another great way to teach this subject is by detailing a large and complex project, walking the reader through the process of achieving the IA goals (it's easier to extrapolate from the complex to the simple than the other way around). The webinars talked about a university application for example, but expound on that and in particular explain how basic D7 and the usual assortment of Drupal modules isn't quite up to the task, requiring tighter integration of the chosen tools to automate a lot of what OA2 does such as spaces and sections being content aware through various contexts and also respecting a complex hierarchy of groups of users and roles.
As someone famous once said, "How can you know where you're going if you don't know where you came from".
I'm exhausted already. Time for a beer...
Comment #15
Argus commentedI was more thinking of a practical user guide, the user being the site builder here. There is no need to explain all contrib modules etc OA2 is build upon. We can refer to known documentation about those if needed, it is important to focus on what OA2 brings to the table.
For starters I added a section "Webinars summaries" to the documentation pages, that will list important webinars and a per minute summary so it is easier to find specific info without having to go through the entire webinar.
First webinar added: https://www.drupal.org/node/2290221
Comment #16
druplicate commentedWell, even a site builder needs to know a certain amount of inner workings.
My guess is most people won't use OA2 out of the box and will want to customize it and for that you need to know more than just pushing a few buttons and twisting some dials.
Suppose you had a set of requirements that OA2 was well suited for but OA2 didn't exist. How would you go about building the equivalent? You might decide not to use Features, OG, Panopoly or Panels but still be able to get similar functionality with Views, relationships, entity references, roles, and taxonomy. It's pretty hard to customize OA2 without knowing how it was built.
A lot of site builders have never used OG, Panopoly, Panels, or Features and will be confused by the many configuration options that are spread all over the place, particularly daunting if you want to customize something but don't know if it should be put in a Features override. Trying to figure out Features, OG, Panels and Panopoly all at once is a lot of work and you can't have a good working understanding of OA2 without knowing at least why they were chosen.
For instance, I want to create yet another distribution based on OA2 but I'm having serious reservations because of the complexity. For example, when should I create a new content type VS modifying a Space or Section type and account for the differences in a Features override? Why is taxonomy used to organize sections and is that the best (or only) way to do it? Understanding information architecture is a big part of the learning curve and knowing how OA2 helps is critical to achieving that.
You don't have to explain how Features, OG, Panels, or Panopoly work in detail, just how they relate to OA2 and what they bring to the table, and explain from which of those components every configuration option or page comes from.
Maybe start with the physics department setup (and a requirements document) from the webinars but make it more complex with a few added custom content types and so forth. Illustrate the thinking process that one would go through to build the IA required just using basic Drupal but coming up short. Show how OG gets you the hierarchy of groups (spaces) and subgroups (sub spaces) and how it was customized for OA. Show how Panopoly simplifies the Panels UI, and how Panelizer is a great end-user tool. Show how taxonomy and entity references tie sections in with spaces. Explain how the Panels Swiss army knife makes custom layouts a snap.
Basically walk the reader through a very complete and complex IA requirement to show how and where every component of OA works. Asking the site builder to go bone up on OG, Panopoly, Panels, and Features isn't going to get people using OA, and using it is how you'll learn it best. With a worked out complex IA scenario the user can extrapolate to their own application.
Comment #17
jakeschlachter commented+1 for comment #16.
In my experience, OA2 is an abstraction above a lot of complex moving parts, and abstractions leak. As a site builder, it's been my experience that OA2 is not implementable until you well understand the underlying complexity, which produces a pretty tall learning curve once you start counting modules. I think that good documentation would include fundamentals of OA2's architecture as a starting-out point for further customization.
Comment #18
jkingsnorth commentedIn #2021675: Fix Bugs in Internet Explorer 9 erok415 suggests splitting the installation/upgrade page into 3 sections: Installation / Upgrading / Troubleshooting. I think this is a sensible suggestion. I'm happy to give it a shot unless someone else beats me to it.
Comment #19
erok415 commentedHi Team,
Thanks .John, I'm happy to do it to. Let me know.
E.
Comment #20
jkingsnorth commentedWell there's two of us in agreement at least, I'm not a maintainer of the project but I reckon go for it =]
Comment #21
erok415 commentedHi Team and .John,
I made the changes to all of the documentation. I'd like to add more troubleshooting documentation as we aggregate it internally at our own helpdesk. As we aggregate them, I'll push what I can to the documentation now that it's better structured. I think the community will find it easier to digest in small chunks rather than larger. This also helps to give clearer instructions since only the instructions that they need for their situation will be on one page.
If I've done anything that needs addressing, please either update it yourself or make suggestions. I'm happy to help (noting that updating the forums is not my day job ;) ).
E.
Comment #22
jkingsnorth commentedComment #23
Parkview-1 commentedIf you were wondering which webinar mpotter is referring to in #5 that explains how to change the logo, it's this one http://docs.openatrium.com/open-atrium-webinars/10-tips-tricks-using-ope...
Customizing the appearance is dealt with in tip #3 that starts at 16:24 in the webinar.
Comment #24
Argus commentedGreat you did anyhow, thanks!
Comment #25
mpotter commentedClosing this issue since the documentation of the install and update process was completed (thanks to John.K and others!).
Comment #26
Argus commentedReopening, the documentation should not only cover the install and update process alone.
Comment #27
Argus commented