search

Strider-CD / strider

Open Source Continuous Integration & Deployment Server
http://strider-cd.github.io/
4.6k stars 432 forks source link

Wiki page link for every in-app screen #208

Open jaredly opened 10 years ago

jaredly commented 10 years ago

I think 1.4 will in many ways be our debut, and we need killer documentation and a website that really makes it clear how awesome strider is.

Examples of awesome documentation:

Currently strider-cd.github.io reroutes to stridercd.com, which does not correspond to a gh-pages anything. Could we get docs.stridercd.com which does map to the gh-pages? Or maybe just remove the redirect so strider-cd.github.io does the normal thing?

niallo commented 10 years ago

Agreed. How about stridercd.com/docs? We could have that auto-generate from a repo. Perhaps use sphinx or something similar? We can provide hosting of docker images or whatever to do this. I found github pages not all that reliable so probably better to self-host.

However I'd caution we should be careful not to bite off more than we can chew for the 1.4 release. Let's not couple a slick website directly to the software version.

We should quietly get the code out there, make sure it's stable, develop a solid list of plugins, work on docs.

When we are ready for the attention, we can have a more "marketing"-focused release (perhaps under the moniker Strider 2).

peterbraden commented 10 years ago

I'm in favor of docs.stridercd.com forwarding to stridercd.github.io - it'd be nice to have the docs in the repo, and do something awesome with them.

Happy to spearhead this...

Peter Braden

http://PeterBraden.co.uk

On 15 October 2013 07:56, niallo notifications@github.com wrote:

Agreed. How about stridercd.com/docs? We could have that auto-generate from a repo. Perhaps use sphinx or something similar? We can provide hosting of docker images or whatever to do this. I found github pages not all that reliable so probably better to self-host.

However I'd caution we should be careful not to bite off more than we can chew for the 1.4 release. Let's not couple a slick website directly to the software version.

We should quietly get the code out there, make sure it's stable, develop a solid list of plugins, work on docs.

When we are ready for the attention, we can have a more "marketing"-focused release (perhaps under the moniker Strider 2).

— Reply to this email directly or view it on GitHubhttps://github.com/Strider-CD/strider/issues/208#issuecomment-26341515 .

peterbraden commented 10 years ago

On the other hand, github pages kinda suck as they are in a separate branch thus they can get out of date pretty easily. Perhaps we do just build them from whatever is in the docs folder - the public strider instance can rebuild on every commit.

peterbraden commented 10 years ago

Bootstrap uses gh_pages, docker uses sphinx.

jaredly commented 10 years ago

for a lot of front-end devs, markdown is more accessible, but the difference isn't that huge.

On 10/15/13, Peter Braden notifications@github.com wrote:

Bootstrap uses gh_pages, docker uses sphinx.

Reply to this email directly or view it on GitHub: https://github.com/Strider-CD/strider/issues/208#issuecomment-26377663

peterbraden commented 10 years ago

I agree - markdown is preferable

niallo commented 10 years ago

Any thoughts on this? I'd love to start working on docs. I've used Sphinx before but I don't care much about the specifics of the tool.

jaredly commented 10 years ago

I'd vote for github pages + markdown. We can look at bootstrap's docs as a template

On Tue, Oct 22, 2013 at 2:59 PM, niallo notifications@github.com wrote:

Any thoughts on this? I'd love to start working on docs. I've used Sphinx before but I don't care much about the specifics of the tool.

— Reply to this email directly or view it on GitHubhttps://github.com/Strider-CD/strider/issues/208#issuecomment-26847847 .

peterbraden commented 10 years ago

let's just start writing docs in markdown in the repo - we can always work on nicer layout later, but the content is the priority

jaredly commented 10 years ago

sounds good

On 10/22/13, Peter Braden notifications@github.com wrote:

let's just start writing docs in markdown in the repo - we can always work on nicer layout later, but the content is the priority

Reply to this email directly or view it on GitHub: https://github.com/Strider-CD/strider/issues/208#issuecomment-26849747

shaunc commented 9 years ago

I was looking for a CD tool and strider comes out as one of the top candidates. I like the architecture, and there seems to be a fair amount of active development... but all documentation seems to be aimed at strider developers, not actual strider users? The "book" starts out well but just has a few pages.

In particular, what are the configuration defaults? I've created an admin user, typed "npm start" ... now what? where is my dashboard? How do I create a project?

Is strider just a captive project for docker (and/or etc?) If not, I must admit I'm puzzled. Why have you spent so much effort (and seem to still be putting effort into) creating strider but almost none telling anyone how to use it?

kfatehi commented 9 years ago

Great questions. My answer/excuse is that I'm a terrible marketer and the feedback to prompt surgical additions to the docs have been, for the most part, lacking altogether.

To me it feels like Strider is a Dev (or Ops, or devops) tool and so generally when you find it, and discover the plugin system, you become a strider developer yourself, since you are a developer yourself already and are thus capable.

This is how it went for me, yes the docs suck, but having become an important passion project to me, Strider was worth bumping into walls to master. On Sat, Nov 29, 2014 at 1:23 AM Shaun Cutts notifications@github.com wrote:

I was looking for a CD tool and strider comes out as one of the top candidates. I like the architecture, and there seems to be a fair amount of active development... but all documentation seems to be aimed at strider developers, not actual strider users? The "book" starts out well but just has a few pages.

In particular, what are the configuration defaults? I've created an admin user, typed "npm start" ... now what? where is my dashboard? How do I create a project?

Is strider just a captive project for docker (and/or etc?) If not, I must admit I'm puzzled. Why have you spent so much effort (and seem to still be putting effort into) creating strider but almost none telling anyone how to use it?

— Reply to this email directly or view it on GitHub https://github.com/Strider-CD/strider/issues/208#issuecomment-64936136.

kfatehi commented 9 years ago

Almost forgot: Strider has great Docker support because it has a well designed modular architecture. It was invented long before Docker was "a thing" -- but I'd love to hear more about this concept of a "captive project" if you have some time to explain it. On Sat, Nov 29, 2014 at 1:31 AM Keyvan Fatehi keyvanfatehi@gmail.com wrote:

Great questions. My answer/excuse is that I'm a terrible marketer and the feedback to prompt surgical additions to the docs have been, for the most part, lacking altogether.

To me it feels like Strider is a Dev (or Ops, or devops) tool and so generally when you find it, and discover the plugin system, you become a strider developer yourself, since you are a developer yourself already and are thus capable.

This is how it went for me, yes the docs suck, but having become an important passion project to me, Strider was worth bumping into walls to master. On Sat, Nov 29, 2014 at 1:23 AM Shaun Cutts notifications@github.com wrote:

I was looking for a CD tool and strider comes out as one of the top candidates. I like the architecture, and there seems to be a fair amount of active development... but all documentation seems to be aimed at strider developers, not actual strider users? The "book" starts out well but just has a few pages.

In particular, what are the configuration defaults? I've created an admin user, typed "npm start" ... now what? where is my dashboard? How do I create a project?

Is strider just a captive project for docker (and/or etc?) If not, I must admit I'm puzzled. Why have you spent so much effort (and seem to still be putting effort into) creating strider but almost none telling anyone how to use it?

— Reply to this email directly or view it on GitHub https://github.com/Strider-CD/strider/issues/208#issuecomment-64936136.

shaunc commented 9 years ago

"Captive project" -- just that when googling around for info, I found more info on strider in docker than on strider per se. I don't know who you or the core strider or docker devs are but one hypothesis was that this was a public repo "thrown over the wall" and that is why you didn't bother to document the system as such but still found the time in your busy lives to write & maintain lots of code.

... anyway: as I said I was drawn to the architecture -- I can imagine that flying at cruising altitude is quite nice. But takeoff is still pretty bumpy! I've been building a project w/ manual tests, but am now about to deploy it. In preparation to shifting from building to maintaining, I wanted a nice, simple, modular continuous development system written in either node (best) or python (2nd best), which I could later add tasks (such as deployment) to simply but now could get up and running fast. You and buildbot came to the top of the list.

I'll fiddle with it for the rest of the day... but if it takes me more than a day to get running I'll go on to buildbot. [right now I found the dashboard, but cant seem to create a git project pointed at my gitosis repo... hmm... where is the project data stored -- in mongo? so why is it asking me about a cache between runs...?]

shaunc commented 9 years ago

So, um.. prompt for surgical additions: :)

On projects/manual add tab, could you give an example of what valid entries look like? 1) what is the "public" button for? 2) "display URL" is this url of project dashboard? So just a path, or a real url? But what about the URL of my git repo? 3) Name: seems to turn red no matter what I type. 4) URL ... hmm... so this isn't the caching URL? Ah maybe its the repo url :) ... can I use git://? 5) ... um... create button still doesn't seem to work. Hmm... name field is red still. Breakpoint in the "create" function never hit...

shaunc commented 9 years ago

Ok ... so a look at the html code reveals that not only does the URL require one slash but the slash must be in between two words. (regex pattern /[\w-]\/[\w-]/ ). ... hmm... ok something happened. :) Still not very intuitive -- the two words are um root project and subproject? Or what?

shaunc commented 9 years ago

Ok ... first test working :)

SO -- PLEASE -- if you could spend 15 min documenting projects/manual add I'm sure you will get a lot more people coming in the door. 1) the "display URL" -- what is it anyway -- do you have express listen here as well? Anyway I just put in "foo" and its fine with it. I thought I should put my repo URL here though as that was the URL I thought I'd need. 2) name -- still don't know why exactly two names, but it works. Error msg and explanation would preclude having to look at the html. I first tried /foo and foo/ which both have one slash as the instructions say.... 3) "caching" -- I guess whether you clone anew each time or just pull on subsequent. Fine.... 4) "URL" -- where you really put in the project url: I understood "caching" as a section heading, so thought that this was something to do with caching.

shaunc commented 9 years ago

Suggestion on breaking down doc into pieces: For each strider screen, there should be a link from that page that goes to a wiki page for that screen. Create the wiki pages and fill with "todo". Now your community can submit pull requests with doc written on these pages whenever they discover how they work :)

jaredly commented 9 years ago

@shaunc Thanks for the suggestions!

1) we provide a link in the UI if you put a url there, so you can easily jump to viewing the repo on github or wherever 2) a carry-over from when we were more closely tied to github. Has to do with routing 3) exactly. git clone vs git pull

jaredly commented 9 years ago

Ooh that's a really good idea! Thanks

bitwit commented 9 years ago

Totally agree the docs need work. I got drawn to Strider for its simplicity to get going, but there were still a lot of little questions and I think that especially if you are coming more from the dev side than the ops side, you need more guidance to get started with a self hosted CD system.

Great suggestions from @shaunc

niallo commented 9 years ago

Great suggestions for sure. I definitely agree that docs are Strider's biggest weakness. I can take responsibility for that since I didn't personally write good documentation when I started the project.

I did begin the Strider book, however the reality is I didn't have time to finish that on my own. Writing an entire book is a huge commitment.

However perhaps if we can just get the ball rolling, then people in the community can feel empowered to participate and the effort will snowball. I like the Wiki approach for that reason. Having a mapping from screen to wiki page is a great idea.