List of Projects WebsiteOne Features request and design Documentation Review for "New users - Getting Started"

Documentation Review for "New users - Getting Started"

Updated over 4 years ago by Christian

I haven’t yet got through the entire agileventures site, but covered, Articles and Projects/websiteone/documents.

I started in this Document, but then moved to a spreadsheet with articles/documents listed, because it was better to show the heir achy, and it has some further comments.

Maybe the spreadsheet is better suited ?

There’s good content, but some documents are a little hidden and difficult to find. ?

Comments

Gives all articles but in a random order (most recently updated order), there's no way to sort Alphabetically or select by Project, only by Tags (and only one) can be used to filter.

Project names are not a Tags.

Project links would be useful in the side panel too. Maybe lofi solution is to add Project Names on this page as links to allow direct navigation to find articles about a project.


It’s not obvious, that clicking all articles, doesn’t give you a list of all the available documentation, only he top level Articles are listed.


There is currently no way to to get an index of all articles.


Is there any implementation difference between articles and documents? Could we tag Documents so that they appear here ? (at the top level articles level).


It would be a useful to have a link to articles Tagged : “Getting Started” ,..


Agile Ventures should take me to a set of articles that common to all projects, ordered relevantly: We currently get:

  • Project Setup (New Users)

  • Crowdsourced Learning

  • Scrum checklists - distributed teams

Project Setup looks like a promising article, but it’s content doesn’t live up to it’s title (see further critique regarding this particular article below).

It mentions many Tools, but only describes Github :-(

It finishes too early, without instructing to create a Feature Branch and not making changes to develop branch.

I suggest creating an article with a title like “Getting started 1-2-3” as a top level How to get going with Agile Ventures. ie. Scrum-Pair-Environment.

New Article Setting up your Development Environment, covering

  • Tools
  • Getting Started with our Github Projects


  • Somewhere, we need to mention what tools we use for each purpose;

Bugtracking => PivotalTracker

Sign up, and apply to join/get added to the xxx Project here.


Repostory => Github.

  • Sign up at Github.

  • Follow these instructions, new Article: Get Started with our Gitub projects.


Pairing => Google Hangouts, Read, Get Started with Hangouts


Source Control tool => git, installed during Setup of Project dev Environment


Communication => Slack chat, sign up for a Slack account and apply for Agilventure’s membership here.


Design Documentation => wiki ? Agilventure’s Project “deep down the heirachy” Design Document ?


  • New Article: Getting Started with our Github Projects

    • Forking

    • branches master, staging, development How they are used. What not to do.

    • cloning your Github repo for local development

    • working on a feature branch

    • edit-add-commit Cycle

    • fetch-rebase Cycle

    • pull request

    • fixing changes on a pulled request

  • New Article : Get Started with Hangouts

  • New Article : Get Started with Agilventures

    • 1 => 2 => 3 =>

    • Attend a Scrum Introduce yourself and get some help.

    • Setup your Dev Environment

      • Tools and Accounts

      • Vagrant Virtual Box

      • Organise your Source Code

    • Pair

      • You can even pair on setting up your environment.

  • New Article : Synching your Feature branch with Upstream (Similar to https://help.github.com/articles/syncing-a-fork).

  • To help visualise the current documentation I have listed them. See document list spreadsheet (Only Articles and websiteone project documents have been reviewed).


Further suggestions from a 2nd reviewer, Nikita Avvakumov

As an incoming member, it would have been useful to see something like the following:
  • A general 'Getting Started' guide with instructions common to all AV projects: set up a profile, sign up for GitHub, G+, Pivotal Tracker, Slack etc. It now exists, but is somewhat long in my opinion.

  • Well-crafted landing pages for active projects. Project description, development strategies and tools in use, timeline of milestones, etc. summarized in 2-3 paragraphs. These cannot be buried in associated documents. This point was brought up by Christopher in the WSO dev meeting, by me in response to Yaro's request for AV Mission & Goals, and I cannot emphasize it enough.

  • A link to a project-specific 'Getting Started' guide on the project's home page. The guide contains PT & GitHub links, setup scripts, scrum schedules, contact info for project leads, etc.


In keeping with AV's philosophy, all guides should emphasize that existing members will be happy to walk a new member through the setup via a pairing session; however, the guide is provided for those who do not feel comfortable coming into a scrum/PP session without any preparation.


I am strongly in favour of leanness and clarity, so to me the empty 'Scrums' document and unmaintained 'Load tests' and 'Client meetings' with a single sub-document each detract from the WSO image rather than add to it.


A minor change that would improve UX is to rename parent documents, which usually have no content, into "folders" or "directories" - i.e. natural containers for child documents.





Revisions

comments powered by Disqus