Even more Ubersicht

[boennemann]

Hello team Hoodie (:

I wanted to give you some feedback on my experience with getting started.

First of all the website really is excellent for the bigger scope of the project and doing the first few steps, but once I started digging deeper, or running into problems it turned out that the information is spreaded across too many locations and fragmented.

You already realized that it's hard to stay on top of issues across all the repositories and that's why Ubersicht came to life. While it's without question a super awesome tool, it's focused more on team members, or people who are already into hoodie.

It's totally reasonable, even necessary, to have that many repositories. I just couldn't find one central description of which module does what (I know this might seems obvious, but still), how they matter to me as a user, how I interact with them, where to look for existing issues, create new ones and which readmes to read.

Which leads me right to the next point – Readmes. Many of the repositories have their own readme, beginning with a general introduction to hoodie. It doesn't seem like the general intros are synced between the repos or the website which makes it hard to keep them up to date and as a reader I get the impression that I've already read them. That way I might skip over essential information. @janl already started a discussion about versioning in #17 where he states that even though the modules are versioned independently they are associated with a certain hoodie release.

I propose to have one central Readme that contains examples, troubleshooting etc. that matter to the user, together with the submodule description I mentioned earlier (This should also be the one that is distributed with my-first-hoodie). The specific repos' readmes should only contain information relevant for development and maintenance.

I know you don't want to use version numbers for marketing and that's a good thing imho. Nonetheless it would benefit developers to communicate releases transparently (also please employ pre-release flags if something is unstable, untested or super new), so they can troubleshoot better, and ultimately report bugs that are specific to a certain version. Changelogs would be awesome, too. I guess the Angular team already nailed that with their commit message conventions and automatic changelog generation.

As discussed in hoodiehq/hoodie#212 and #31 of course the project would benefit from a source generated documentation for both the frontend and server API as well as more in depth and profound deployment instructions.

I hope my feedback is relevant to you and I'd love to help fixing stuff.

Best,
Stephan

[janl]

@boennemann this is fantastic feedback. Thank you so much for taking the time to write it all up after having the patience of going through all the mazes we put up for you :)

I know we have a documentation and organisation effort going on that should help address at least some of the issues you mention :)

For the rest, we’ll look for a solution as well.

Thanks again!

[lewiscowper]

I really like the idea of a single readme file, that sounds like the sort of thing that I can really sink my teeth into. Also it's something we can refer to throughout other docs, as a "for more info look here" kind of document, plus it's something that hood.ie could use for sure. Ideally (not sure about how possible this is), we could use the main readme as the docs in hood.ie, and get hood.ie to pull that file in direct from the repo.

[davidpfahler]

This issue is stuck in "that would be great" mode. I do think this is of greatest importance to hoodie (feel free to disagree; just my outsiders opinion). I, for example, have the biggest troubles finding where stuff is, what is latest and what is outdated, which docs and readmes to trust and which are just dreamcode, etc.

I think the problem here is that

1. it's hard to tell what the next actions are and
2. it's hard to find someone who could do it.

Open questions I can think of:

• Do we want one readme for using hoodie and one for developing it or both in one file?
• How does the website and docs.hood.ie play into this readme?
• Who has the proper overview over the project so they are able to write down and explain how it all works together? Is there even such a person who can still understand all the pieces?

@janl Maybe you can give us who are using hoodie and not in the core team some insight into what the roadmap is regarding these questions?

Thanks in advance. <3

[janl]

all this is currently being addressed in the website and documentation refactor ;)

On 17 Jul 2014, at 15:16 , David Pfahler notifications@github.com wrote:

This issue is stuck in "that would be great" mode. I do think this is of greatest importance to hoodie (feel free to disagree; just my outsiders opinion). I, for example, have the biggest troubles finding where stuff is, what is latest and what is outdated, which docs and readmes to trust and which are just dreamcode, etc.

I think the problem here is that

1. it's hard to tell what the next actions are and
2. it's hard to find someone who could do it.

Open questions I can think of:

• Do we want one readme for using hoodie and one for developing it or both in one file?
• How does the website and docs.hood.ie play into this readme?
• Who has the proper overview over the project so they are able to write down and explain how it all works together? Is there even such a person who can still understand all the pieces?
@janl Maybe you can give us who are using hoodie and not in the core team some insight into what the roadmap is regarding these questions?

Thanks in advance. <3

—
Reply to this email directly or view it on GitHub.

[davidpfahler]

@janl Is this on github? where can I find that?

[janl]

cc @ffffux

On 17 Jul 2014, at 16:11 , David Pfahler notifications@github.com wrote:

@janl Is this on github? where can I find that?

—
Reply to this email directly or view it on GitHub.

[lenareinhard]

@davidpfahler Hi, I'm the person with the overview over these parts of Hoodie.

We're completely aware there are currently many issues with the website, the docs, the general overview and displaying opportunities for contributors (aside from Ubersicht http://espy.github.io/ubersicht/#hoodiehq ). What we got now, is a team of 6 working on our website relaunch (some in full-time, some as part-time supporters and contributors) and a team of 7 working on the docs, plus people working on the roadmap etc. pp.

What we'll be doing in the new website:

• completely new structure
• far more content, all in one place (still generated e.g. from content on GitHub)
• redesign
• a new structure addressing people's skills and (probable) needs, and lead them to the content they need
• how to support Hoodie (with special, detailed "where and how to contribute" section)
• far, far more beyond that

What we're currently working on in addition:

• updated roadmap with detailed issues, owners and people who are assigned (current version is here Roadmap #38, new version tba)
• documentation (see issues https://github.com/hoodiehq/documentation and repo https://github.com/hoodiehq/documentation) – the docs will also be deeply embedded in the new website
  We're aiming to display content on a central place, without creating maintenance overhead content-wise. Thus, I don't know yet if the solution to what has been adressed in this issue is a central Readme file, but will talk to the docs team about this.

Please note that the website relaunch project is not on GitHub. We're working mostly with designers (and designers / developers) and had asked them for their preferred collaboration platform and finally decided to not use GitHub as it's not really useful for design tasks, and also in terms of allowing them to focus.

I hear you and understand your concerns and the need to have all of this as fast and transparent as possible. We're trying to address all those issues you brought up as good as we can.

[gr2m]

@davidpfahler For the time being, I'm happy to chat to give answers to your questions first hand, just ping me on Twitter: twitter.com/gr2m. Thanks for taking the time to give us your outside perspective, that is very useful indeed!

[davidpfahler]

@ffffux @janl @g2m I'm convinced you are all doing your best and making great progress. No question about it. All I'm trying to do is to find - with an outsiders perspective - potential breakpoints for the user experience of using hoodie. It's great to see you put so much effort in docs and the website now. There is value in knowing that this is coming.

So we'll revisit this issue once docs and website are released and see what we can improve?

[janl]

@davidpfahler please just keep going and send anything you can find, it will make Hoodie a lot better. We are very grateful for your support! <3 :)

[lenareinhard]

@davidpfahler very much +1 on hearing your input, this is so helpful for us who have already dived too deep into the project :) In addition: If you have resources for that, I'd also love to hear your feedback on the new content structure (meaning: website + docs) in maybe four weeks or so, if this works for you, so we can improve the new setup. I'll also ask other people for feedback, but would love to have yours, too. Just think about it, maybe we can make this happen.

[davidpfahler]

@ffffux I'd be happy to give in-depth feedback on the website, docs etc. Just ping me when you think it makes sense.

[gr2m]

We addressed most of these points meanwhile :) I’m gonna close it as part of my issue triaging